<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<title>query_script_try_catch: common_schema documentation</title>
	<meta name="description" content="query_script_try_catch: common_schema" />
	<meta name="keywords" content="query_script_try_catch: common_schema" />
	<link rel="stylesheet" type="text/css" href="css/style.css" />
</head>

<body>
	<div id="main">
		<div id="header">
			<h1>common_schema</h1> <strong>2.2</strong> documentation
			<div class="subtitle">DBA's framework for MySQL</div>
		</div>
		<div id="contentwrapper">
			<div id="content">
				<h2><a href="query_script_try_catch.html">query_script_try_catch</a></h2>	

<p>
QueryScript Flow Control: <strong>try-catch</strong> statement
</p>

<h3>SYNOPSIS</h3>
<p>
<blockquote><pre>try
  statement;
catch
  statement;
</pre></blockquote>
</p>

<h3>DESCRIPTION</h3>
<p> 
<i>try-catch</i> is an error handling flow control structure. Flow is determined based on
the appearance or non-appearance of execution errors. 
</p>
<p>
The <strong>try</strong> statement (or block of statements) is executed. If no error occurs, it completes, and the
<strong>catch</strong> statement is never executed.
</p>
<p>
If an error is detected within execution of the <strong>try</strong> statement, the <strong>try</strong> statement is aborted
at the point of error (i.e. all statements following the point of error are discarded), and the
<strong>catch</strong> statement (or block of statements) is executed.
</p>
<p>
An error thrown from within a <strong>catch</strong> is not further caught, unless surrounded in itself by a nested <strong>try-catch</strong> statement.
</p>

<p>
The <strong>catch</strong> block executes upon any error thrown within the <strong>try</strong> statement. It is not possible, at the moment, to explicitly
specify a type of error for which the <strong>catch</strong> block should operate. Nor is it possible to specify multiple <strong>catch</strong> blocks as
is common in various programming languages.
</p>
<p>
Furthermore, it is currently not possible to retrieve the exact error (or error code) causing the <strong>catch</strong> block to operate. All that is known is that
<i>some</i> error has been raised.
</p>

<p>
Empty statements are not allowed in QueryScript. However, empty blocks are, and the 
<i>try-catch</i> clause may be followed by an empty block, or by the do-nothing <a href="query_script_pass.html">pass</a> statement.
</p>

<p>
Though syntactically valid, it makes no sense to use an empty <strong>try</strong> statement. It does make perfect sense to use an
empty <strong>catch</strong> statement, to the result of silencing an error without termination of the script.
</p>

<h4>Nesting</h4>

<p>It is possible to have nested <strong>try-catch</strong> statements. When nested, errors are caught by 
the deepest <strong>catch</strong> block which applies to them.
To illustrate, consider:
<blockquote><pre>
try {
  statement1;
  try {
    statement2;
  }
  catch {
    -- errors in statement2 are handled here
    statement 3;
  }
  statement 4;
}
catch {
  -- errors in statement1, statement3 and statement4 are handled here
  -- errors in statement2 are not handled here
  statement 5;
}
</pre></blockquote>
</p>

<p>Unlike other common implementations of <strong>try-catch</strong>, <i>QueryScript</i> does not
require block statements, i.e. braces. This allows for the following <i>try all you can</i> syntax, 
which is very similar to a nested <i>if-else-if-else</i> construct:
<blockquote><pre>
try {
  statement1;
}
catch try {
  -- We only get here if statement1 fails
  statement2;
}
catch try {
  -- We only get here if statement1 & statement2 fail
  statement3;
}
catch try {
  -- We only get here if all previous statements fail
  statement4;
}
catch {
  -- They all failed
  statement5;
}
</pre></blockquote>
</p>

<h3>EXAMPLES</h3>
<p>
Simulate a schema upgrade process: try and create a table. If it already exists, make sure a given column is upgraded to a desired type:
<blockquote><pre>
try
{
  -- Try and create table:
  CREATE TABLE test.article (
    article_id int unsigned NOT NULL AUTO_INCREMENT PRIMARY KEY,
    title varchar(128) CHARSET utf8,
    content text CHARSET utf8
  );
}
catch
{
  -- Apparently table already exists. Upgrade it:
  ALTER TABLE test.article
    MODIFY COLUMN content text CHARSET utf8;
}
</pre></blockquote>
</p>

<p>
Repeat attempts for query which is expected to abort on deadlock: insist on executing it until successful:
<blockquote><pre>
while (true)
{
  try
  {
    -- Attempt query which is expected to abort on deadlock:
    UPDATE some_table SET some_column = 1 WHERE some_condition;
    -- Got here? This means query is successful! We can leave now.
    break;
  }
  catch
  {
    -- Apparently there was a deadlock. Rest, then loop again until succeeds
    sleep 1;
  }
}
</pre></blockquote>
</p>

<h3>NOTE</h3>
<p>
Since it is impossible to know the nature of the error causing the <strong>catch</strong> block to execute, and since <i>any</i> error
will cause it to execute, it is the user's responsibility to deduce the origin of the error. In particular, watch out for plain syntax error, or
otherwise SQL errors, such as misspelling table or column names.
</p>

<h3>SEE ALSO</h3>
<a href="query_script_if_else.html">if-else</a>,
<a href="query_script_throw.html">throw</a>

<h3>AUTHOR</h3>
Shlomi Noach


				<br/>
			</div>
			<div id="sidebarwrapper">
				<div id="search">
					Search online documentation
					<form id="search_form" name="search_form" method="GET" 
						action="http://www.google.com/search" 
						onsubmit="document.forms['search_form']['q'].value = 'site:http://common-schema.googlecode.com/svn/trunk/common_schema/doc/html/ '+document.forms['search_form']['search_term'].value;">
						<input type="text" name="search_term" value=""/>
						<input type="hidden" name="q" value=""/>
						<input type="submit" value="go"/>						
					</form>
				</div>
				<div id="menu">
					<ul>
						<li><a title="Introduction" href="introduction.html">Introduction</a></li>
						<li><a title="Documentation" href="documentation.html">Documentation</a></li>
						<li><a title="Download" href="download.html">Download</a></li>
						<li><a title="Install" href="install.html">Install</a></li>
						<li><a title="Risks" href="risks.html">Risks</a></li>
					</ul>						
					<h3>QUERY SCRIPT</h3>
					<ul>
						<li><a title="QueryScript" href="query_script.html">QueryScript</a></li>
						<li><a title="Execution" href="query_script_execution.html">Execution</a></li>
						<li><a title="Flow control" href="query_script_flow_control.html">Flow control</a></li>
						<li><a title="Statements" href="query_script_statements.html">Statements</a></li>
						<li><a title="Expressions" href="query_script_expressions.html">Expressions</a></li>
						<li><a title="Variables" href="query_script_variables.html">Variables</a></li>
					</ul>						
					<h3>DEBUG</h3>
					<ul>
						<li><a title="rdebug" href="rdebug.html">rdebug</a></li>
						<li><a title="rdebug API" href="rdebug_api.html">rdebug API</a></li>
						<li><a title="rdebug workflow" href="rdebug_workflow.html">Workflow</a></li>
					</ul>						
					<h3>ROUTINES</h3>
					<ul>
						<li><a title="Execution &amp; flow control" href="execution_routines.html">Execution & flow control</a></li>
						<li><a title="General" href="general_routines.html">General</a></li>
						<li><a title="Process" href="process_routines.html">Process</a></li>
						<li><a title="Query analysis" href="query_analysis_routines.html">Query analysis</a></li>
						<li><a title="Schema analysis" href="schema_analysis_routines.html">Schema analysis</a></li>
						<li><a title="Security" href="security_routines.html">Security</a></li>
						<li><a title="Text" href="text_routines.html">Text</a></li>
						<li><a title="Time &amp; date" href="temporal_routines.html">Time & date</a></li>
						<li><a title="Charting" href="charting_routines.html">Charting</a></li>
					</ul>
					<h3>VIEWS</h3>
					<ul>
						<li><a title="Schema analysis" href="schema_analysis_views.html">Schema analysis</a></li>
						<li><a title="Data dimension" href="data_dimension_views.html">Data dimension</a></li>
						<li><a title="Process" href="process_views.html">Process</a></li>
						<li><a title="Security" href="security_views.html">Security</a></li>
						<li><a title="Monitoring" href="monitoring_views.html">Monitoring</a></li>
						<li><a title="InnoDB Plugin" href="innodb_plugin_views.html">InnoDB Plugin</a></li>
						<li><a title="Percona server" href="percona_server_views.html">Percona Server</a></li>
						<li><a title="TokuDB" href="tokudb_views.html">TokuDB</a></li>
					</ul>						
					<h3>DATA</h3>
					<ul>
						<li><a title="tables" href="tables.html">Tables</a></li>
						<li><a title="variables" href="variables.html">Variables</a></li>
					</ul>						
					<h3>META</h3>
					<ul>
						<li><a title="Help" href="help.html">help</a></li>
						<li><a title="Metadata" href="metadata.html">metadata</a></li>
						<li><a title="status" href="status.html">status</a></li>
					</ul>						
				</div>
			</div>	
			<div class="clear">&nbsp;</div>
			
			<div id="footnote" align="center">
				<a href="">common_schema</a> documentation
			</div>
		</div>
	</div>
</body>
</html>
